Developer CD Series 1996 February: Tool Chest/Apple Developer CD Series Tool Chest February 1996 (Apple Computer)(1996).iso/Sample Code/AppsToGo/AppsToGo.docs/=How to write your app

Text File | 1994-09-22 | 39.5 KB | 962 lines | [TEXT/MPS ]

The title of this document should have been:

How to write your application using AppWannabe (or Wannabe for short).

The above is too long for a file name, but obviously the title I used got your
attention.  Now all I have to do is to hold it...

If you have built the libraries and sample applications, you may have already
noted that Wannabe is actually an executable application.  Of course, it does
absolutely nothing useful.  That's your job.

I am assuming that you have built the libraries for your compiler of choice
and the sample starter application Wannabe.

DTS.Lib_strings (or DTSx.strings) contains only a single source file,
StringUtils.c.  StringUtils.c contains some useful string functions.  It allows
you to do various functions that are supplied by sprintf.  The amount of code
you have to link in when you choose sprintf is quite large, however.  The
supplied string functions allow you to easily format and parse string data
without linking a large chunk of code.

It is suggested that you link the StringUtils executable into the code segment
that contains main().  This will guarantee that the string functions are always
resident in memory when you call them.  (MPW make files and project files are
already set up this way.)  If the code isn't in ram when you make a string
call, the loading of the code may cause memory to move or compress.  This
is fine, unless you passed a pointer into an unlocked handle as a string
pointer.  If you point into an unlocked handle, simply calling the function can
move memory, unless it is guaranteed that the code is already in memory.  By
linking it into the same code segment as main(), you guarantee that it is
always in memory.  (All of the sample applications already do this.)


Various libraries can be used without committing to the entire DTS.Lib
application framework.  You can write your own application completely
from scratch and then call any of the code in the above-mentioned files
anytime you want.

Each of the above files has useful stand-alone code you will probably want to
look at, even if you choose not to use the DTS.Lib application framework.

If you choose to use the DTS.Lib application framework, (from now on called
DTS.framework), very much of the application development tasks are already done
for you.

DTS.framework currently supports:
    Multiple windows
    Multiple document types
    File I/O
    Apple Events
    Window/document scrolling
    Hierarchical document architecture
    Infinite undo (undos can optionally be saved with the document)
    Floating palettes
    Viewing window for displaying document objects
    Other document-specific tasks, such as mouseDowns, keyDowns, cursors, etc.

What tasks DTS.framework doesn't directly supply can probably be found in the
DTS utilities, so between the two, many of the aspects of Mac application
development are already complete.


So what is the minimum you have to know to get started?

Above, we discussed the various components of the DTS library code.  So now we
need to know the easiest way to use this code.  The easiest way is to make a
copy of the sample application Wannabe, and start adding code.  Consider Wannabe
an application shell which already correctly uses the DTS.framework and
utilities.  All that is missing is the code that is specific to your
application.  Everything that is generic is already in there.

The best place to start explaining is how to manage documents.  We will start
with a code snippet from Wannabe:

switch (menuItem) {
    case kStdNew:
        gDialogErr = NewDocumentWindow(&frHndl, gAppWindowType, true);
        if (gDialogErr)
            NewDocumentWindow(nil, 'ERR#', false);
        break;
        .
        .
        .


This is right out of the file Menu.c  We get to this code by the user choosing
"New" from the file menu.  The first thing we do is to try to create the new
document.  This is done with the DTS.framework call NewDocument().

NewDocumentWindow() just bundles two framework function together, which are
NewDocument() and DoNewWindow().  AppsToGo document-based windows are created
by first creating the document, and then if that step is successful, the
window for that document is created.

As stated above, DTS.framework can support multiple document types.  The type
of the document we are trying to create is docFileType, which is an OSType.
In Wannabe, docFileType is defined as follows:
    #define docFileType      'DUMD'

'DUMD' stands for DUMb Document.  I consider it dumb because when the document
is saved, it is saved with no content.  The DTS.framework very carefully saves
nothing.  You can then open nothing later.  You can print nothing, etc.
Hopefully, you will remedy this situation.

The third parameter to NewDocumentWindow() tells NewDocumentWindow() that you
want to create a document with a new "Untitled #" style of window title.  The
true indicates to DTS.framework that you want this document to have an untitled
number one greater then the last time that NewDocumentWindow() was called.
No big deal, but I figured you would be curious at this point.

If NewDocumentWindow() succeeds, you're done.  If it fails, you probably want
to pop up an alert stating such.  A single call to NewDocumentWindow() will
do this for you, as well.

One of the fields in the frHndl that is initialized is the fileState.attributes
field.  This field describes various window attributes if a window is opened for
this document.  The default attributes are kept in the global gAppWindowAttr.
If you don't like these attributes, you can change them in the frHndl after it
is initialized and before you give the document a window.

The various values for the attribute field are:

    #define kwGrowIcon            0x00000001L
    #define kwHScroll            0x00000002L
    #define kwHScrollLessGrow    0x00000006L
    #define kwVScroll            0x00000008L
    #define kwVScrollLessGrow    0x00000018L
    #define kwVisible            0x00000020L
    #define kwOpenAtOldLoc        0x00000040L
    #define kwDoFirstClick        0x00000080L
    #define kwHideOnClose        0x00000100L
    #define kwIsDocument        0
    #define kwIsPalette            0x00000200L
    #define kwIsModalDialog        0x00000400L
    #define kwDefaultDocHeader    0x00000800L
    #define kwHeaderIsResource    0x00001000L
    #define kwRuntimeOnlyDoc    0x00002000L
    #define kwAutoNew            0x00004000L
    #define kwDefaultDocType    0x00008000L
    #define kwColorMonitor        0x00010000L
    #define kwSecondaryMonitor    0x00020000L
    #define kwStaggerWindow        0x00040000L
    #define kwCenterWindow        0x00080000L
    #define kwSameMonitor        0x00100000L

So, if you want to create a window with document scrollbars, you just set a few
bits in the attribute field, and you're done.  And yes, kwOpenAtOldLoc
automatically opens the window wherever the user had it when it was closed,
and yes it makes sure that it is at least partially visible on some monitor.
You can find more information elsewhere.  (These bit-fields are setable via
the AppsToGo application editor.  You do no have to set them via code.)

So what is really going on?

NewDocumentWindow() first calls NewDocument().  NewDocument() calls the function
InitDocument(), which is yours (found in File.c).  Here you can check the OSType
of the frHndl, and then make adjustments based on the various document types in
your application.  To dereference to the attributes field for example, given an
frHndl, do like so:  blahAttrs = (*frHndl)->fileState.attributes;

Other changes can be made to the frHndl at this point.  This is where you state
that you don't want certain default behaviors for the document.  Note that you
probably don't want to actually make these choices via code here.  These choices
can generally be made with the AppsToGo application editor.


Assuming that the frHndl got created successfully, the next step for
NewDocumentWindow() is to create the window.  NewDocumentWindow() passes
DoNewWindow() the successfully created (and possibly altered) frHndl.
DoNewWindow() looks up various fields in the frHndl, and creates the window
accordingly.


The prototype for DoNewWindow is:

OSErr    DoNewWindow(FileRecHndl frHndl, WindowPtr *retWindow,
                    WindowPtr relatedWindow, WindowPtr behind);

If DoNewWindow() successfully creates a window, the window is returned in
retWindow, if retWindow is not nil.  Many times you don't really care what the
window that was created is.  In this case, if it is successful, it is now the
new top window.  If the user clicks on it, then you care.  Here you don't.

If DoNewWindow() was unsuccessful at creating the window, you now are left with
a document, frHndl, that has no window.  If this occurs, you want to dispose of
the document, and report an error.

That's all there is to it.  Oh, the remaining parameters to DoNewWindow():
    relatedWindow:    Create the window on the same monitor that holds most of
                    this window. If nil is passed in, create the window on the
                    main monitor.
    behind:            Create the window behind the window indicated.
                    -1 puts it on top.


Now that we understand document creation and window creation using
DTS.framework, here's the rest of the story:


As mentioned above, NewDocument() returns a handle.  This handle is your
reference to the document, thus my favorite variable name for one os these
things:  frHndl (file reference handle).  You don't have to worry about
associating the frHndl with the window that was created for it.  DoNewWindow()
stores the frHndl in the window's refcon field.  Also, you don't have to worry
about which window belongs to a particular frHndl, as the window is stored in
the frHndl, as well.  The document and its associated window both point to one
another.  (You got one, you got the other -- cool.)


Basically, everything that goes on with documents goes on inside the frHndl.
The frHndl is a handle that holds the structure for the document.  Most of this
structure looks like this:

typedef struct {
    OSType                        sfType;
    Boolean                        defaultDoc;
    Movie                        movie;
    short                        movieResID;
    short                        movieFlags;
    Boolean                        movieDataRefWasChanged;
    Boolean                        docDirty;
    long                        modNum;
    long                        modTick;
    Boolean                        readOnly;
    short                        refNum;
    short                        resRefNum;
    FSSpec                        fss;
    short                        windowID;
    WindowPtr                    window;
    PositionWndProcPtr            getDocWindow;
    CalcFrameRgnProcPtr            calcFrameRgnProc;
    ContentClickProcPtr            contentClickProc;
    ContentKeyProcPtr            contentKeyProc;
    DrawFrameProcPtr            drawFrameProc;
    FreeDocumentProcPtr            freeDocumentProc;
    FreeWindowProcPtr            freeWindowProc;
    ImageProcPtr                imageProc;
    InitContentProcPtr            initContentProc;
    ReadDocumentProcPtr            readDocumentProc;
    ReadDocumentHeaderProcPtr    readDocumentHeaderProc;
    ResizeContentProcPtr        resizeContentProc;
    ScrollFrameProcPtr            scrollFrameProc;
    UndoFixupProcPtr            undoFixupProc;
    WindowCursorProcPtr            windowCursorProc;
    WriteDocumentProcPtr        writeDocumentProc;
    WriteDocumentHeaderProcPtr    writeDocumentHeaderProc;
    AdjustMenuItemsProcPtr        adjustMenuItemsProc;
    DoMenuItemProcPtr            doMenuItemProc;
    long                        attributes;  /* Here down is wndContent info. */
    Rect                        windowSizeBounds;
    ControlHandle                hScroll;
    ControlHandle                vScroll;
    short                        hScrollIndent;
    short                        vScrollIndent;
    short                        leftSidebar;
    short                        topSidebar;
    short                        hArrowVal;
    short                        vArrowVal;
    short                        hPageVal;
    short                        vPageVal;
} FileStateRec;


Here's some explanation of some of the fields:

sfType:                    The type of the document you passed to NewDocument() is
                        stored here.

defaultDoc:                Used by application framework to determine if View
                        Hierarchy facility can be used to view the document.

movie:                    These 4 fields are used together.  If the document type
movieResID:                used is of type 'MooV' for either NewDocument or
movieFlags:                OpenDocument, then these fields are used to keep track
movieDataRefWasChanged:    of the movie information for the document.  In addition
                        to this information, the meaning of the field refNum is
                        extended somewhat.  Here's the deal:  Movie files are
                        generally resource-fork-based, but this isn't always the
                        case.  The movie file can be flattened and made to be
                        data-fork-based.  This is so MS-DOS machines can handle
                        the movie file.
                        To be consistent with regular document files, the
                        resRefNum returned by OpenMovieFile (which isn't always
                        a resource refNum) is kept in the field refNum.
                        Normally refNum represents a data fork, but in the case
                        of movies, it may be either a data fork or resource fork
                        reference number.  For regular documents, if you wish to
                        use the resource fork, you use the calls UseDocResFile
                        and CloseDocResFile.  These still work for movies,
                        whether the movie is data-fork- or resource-fork-based.
                        If the movie is resource fork based, then UseDocResFile
                        simply copies the refNum field into the resRefNum field.
                        This is the correct thing to do, as the resource is
                        already opened for the movie.  CloseDocResFile looks at
                        the refNum and resRefNum fields.  If they are the same,
                        then it simply sets resRefNum to kInvalidRefNum.  This
                        is all that is necessary to "close" the resource fork,
                        as you really don't want it to close, since it was
                        opened for the movie.  All of this behavior is simply
                        to allow the various calls to do the appropriate thing
                        when the document is a movie.  You should be able to
                        handle movie files just like regular document files.

docDirty:                Used by the application framework to determine if a
                        "Save before closing" dialog should be displayed.

modNum:                    This is incremented whenever you call SetDocDirty().
                        Some applications find this information useful.
                        Most don't care.

modTick:                Tick count of last modification.  (See modNum).

readOnly:                True if document is opened read-only.  DTS.framework
                        sets this if the document that is selected by the user
                        can't be openeded with read-write access.  DTS.framework
                        asks the user if it is okay to open it read-only.

refNum:                    The file reference number (0 if it is a new document.)

resRefNum:                Reference number of the resource fork of the document
                        file.  Unless you specifically use the resource fork,
                        the document's resource fork isn't opened.

fss                        The FSSpec for the open file (if there is one open for
                        this document.)

windowID:                The resource ID of the 'WIND' resource to be used when
                        DoNewDocument() is called to give this document a
                        window.  windowID is initialized to rWindow, which is
                        defined to be 128.  If you want a different 'WIND'
                        resource for this document, set this field after
                        calling NewDocument(), and prior to calling
                        DoNewWindow().

window:                    When you call DoNewWindow(), if it succeeds at creating
                        a window, it places the window pointer here.

The next fields are the procedure pointers that determine the behavior of the
document.  These fields are initialized to point to the following functions:

For documents:

    getDocWindow:                GetStaggeredWindow
    calcFrameRgnProc:            CalcFrameRgn
    contentClickProc:            ContentClick
    contentKeyProc:                ContentKey
    drawFrameProc:                DrawFrame
    freeDocumentProc:            FreeDocument
    freeWindowProc:                FreeWindow
    imageProc:                    ImageDocument
    initContentProc:            InitContent
    readDocumentProc:            ReadDocument
    readDocumentHeaderProc:        nil
    resizeContentProc:            ResizeContent
    scrollFrameProc:            ScrollFrame
    undoFixupProc:                UndoFixup
    windowCursorProc:            WindowCursor
    writeDocumentProc:            WriteDocument
    writeDocumentHeaderProc:    nil
    adjustMenuItemsProc:        AdjustMenuItems
    doMenuItemProc:                DoMenuItem


For dialogs:

    getDocWindow:                GetStaggeredWindow
    calcFrameRgnProc:            DialogCalcFrameRgn
    contentClickProc:            DialogContentClick
    contentKeyProc:                DialogContentKey
    drawFrameProc:                DialogDrawFrame
    freeDocumentProc:            DialogFreeDocument
    freeWindowProc:                DialogFreeWindow
    imageProc:                    DialogImageDocument
    initContentProc:            DialogInitContent
    readDocumentProc:            nil
    readDocumentHeaderProc:        nil
    resizeContentProc:            DialogResizeContent
    scrollFrameProc:            DialogScrollFrame
    undoFixupProc:                DialogUndoFixup
    windowCursorProc:            DialogWindowCursor
    writeDocumentProc:            nil
    writeDocumentHeaderProc:    nil
    adjustMenuItemsProc:        DialogAdjustMenuItems
    doMenuItemProc:                DialogDoMenuItem


For palettes:

    getDocWindow:                GetStaggeredWindow
    calcFrameRgnProc:            PaletteCalcFrameRgn
    contentClickProc:            PaletteContentClick
    contentKeyProc:                PaletteContentKey
    drawFrameProc:                PaletteDrawFrame
    freeDocumentProc:            PaletteFreeDocument
    freeWindowProc:                PaletteFreeWindow
    imageProc:                    PaletteImageDocument
    initContentProc:            PaletteInitContent
    readDocumentProc:            nil
    readDocumentHeaderProc:        nil
    resizeContentProc:            PaletteResizeContent
    scrollFrameProc:            PaletteScrollFrame
    undoFixupProc:                PaletteUndoFixup
    windowCursorProc:            PaletteWindowCursor
    writeDocumentProc:            nil
    writeDocumentHeaderProc:    nil
    adjustMenuItemsProc:        AdjustMenuItems
    doMenuItemProc:                DoMenuItem

Note that unless gAppWindowAttr is set for a dialog or palette document/window,
all documents will be created with the first set of procPtrs.

(AppsToGo allows you to set a document/window as a dialog or palette, and if
you are using AppsToGo for development, then gAppWindowAttr isn't used.  Instead
the attributes for the document/window description set with AppsToGo are.
AppsToGo allows you to indicate if a document/window should be a dialog
or palette.)

With the exception of the function GetStaggeredWindow, all of the above
functions are part of the application shell Wannabe.  GetStaggeredWindow is a
function in the DTS utilities that opens a window "staggered" from existing
windows.  This allows some of the window to be exposed so that the user can
easily click on the window and bring it to the front.

All of the other functions are part of your application.  They get called by
the application framework at appropriate times.  They don't get called at some
magic moment.  They get called when your application calls DTS.framework to do
something.  DTS.framework does the generic work. The application-specific work
it can't do, and so it calls your application to do that part.

Even for something as supposedly application-specific as drawing the window
content, you still will call DTS.framework to get the job started.  You will
call the function DoImageDocument().  You pass DoImageDocument() a file
reference handle (frHndl).  DoImageDocument() dereferences the frHndl and
gets the value at the field imageProc.  If imageProc is nil, then there is
no imaging procedure for this document, and DoImageDocument() just returns.
If there is a procedure pointer stored in the field imageProc, then that
code is called.

There is no particular magic happening here.  The DoImageDocument() code looks
just as you would expect:

OSErr    DoImageDocument(FileRecHndl frHndl)
{
    ImageProcPtr    proc;
    OSErr            err;

    err = noErr;
    if (proc = (*frHndl)->fileState.imageProc) err = (*proc)(frHndl);
    return(err);
}

If there is an imaging procedure in the file reference, call it.  Otherwise
it just returns noErr.

Initially imageProc has a value.  The initial value is ImageDocument.  The
ImageDocument() function is located in the Wannabe file Window.c.  If your
application only has a single document type, then just place your document
imaging code inside the stub function ImageDocument().  It's that easy.

For the most part, all of the procedure pointers in the frHndl have a "Do"
function.  For example:  If you want to draw the "frame" portion of a window,
you wouldn't call DrawFrame().  You would call DoDrawFrame().  DoDrawFrame()
will look up the procedure pointer, and if it is not nil, it will call it,
just like DoImageDocument() does.


So how exactly does a file reference handle get created?  Again, nothing
magic, but there are a number of steps that need to be understood.


The creation of an frHndl is invoked by the application.  The application
calls either NewDocument() or OpenDocument(), discussed above.  OpenDocument()
calls NewDocument(), so in either case, you are actually calling NewDocument().

I think the easiest way to explain what NewDocument() does is to show the code.
The two key places are marked with •••.  The explanation follows.  Here's most
of the code:


OSErr    NewDocument(FileRecHndl *returnHndl, OSType sftype, Boolean incTitleNum)
{
    long                size;
    FileRecHndl            frHndl;
    FileRecPtr            frPtr;
    Str255                untitled;
    StringPtr            pstr;
    OSErr                err;
    short                i;
    Movie                movie;
    TreeObjHndl            wobj;
    PositionWndProcPtr    windowPlacementProc;
    static short        untitledCount;

    if (returnHndl)
        *returnHndl = nil;

    if (!sftype) {
        if (!returnHndl)
            untitledCount = 0;        /* API trick to allow you to reset the document count. */
        return(noErr);
    }

    err  = memFullErr;                /* Assume that we will fail. */

•••    size = InitDocumentSize(sftype);
        /* Call the application and ask it how big the frHndl should be for
        ** this document type.  We can't know, so we'll ask. */

    if (frHndl = (FileRecHndl)NewHandleClear(size)) {
        /* Create (or try to) the frHndl, initialized to all 0's */

        if (returnHndl)
            *returnHndl = frHndl;

        .
        .
        . This varies, depending on if you are using AppsToGo.
        .
        .

/* Below we fill in the various fields with defaults for the frHndl. */

        (*frHndl)->fileState.modNum = GetModNum();
            /* In case GetModNum gets moved to another code segment, set this value
            ** prior to dereferencing frHndl into frPtr. */

        frPtr = *frHndl;
        frPtr->fileState.sfType                  = sftype;
        frPtr->fileState.modTick                 = TickCount();
        frPtr->fileState.refNum                  = kInvalRefNum;
        frPtr->fileState.resRefNum               = kInvalRefNum;
        frPtr->fileState.fss.vRefNum             = kInvalVRefNum;
        frPtr->fileState.windowID                = rWindow;
            /* The above sets the fileState constants for the document.  Note
            ** that we use a default 'WIND' ID for the expected window resource.
            ** This can be changed later, if the default isn't good enough. */

        if (wobj) {
            frPtr->fileState.windowID      = mDerefWFMT(wobj)->windowID;
            frPtr->fileState.attributes    = mDerefWFMT(wobj)->attributes;
            frPtr->fileState.hScrollIndent = mDerefWFMT(wobj)->hScrollIndent;
            frPtr->fileState.vScrollIndent = mDerefWFMT(wobj)->vScrollIndent;
            frPtr->fileState.leftSidebar   = mDerefWFMT(wobj)->leftSidebar;
            frPtr->fileState.topSidebar    = mDerefWFMT(wobj)->topSidebar;
                /* Set window attributes as described in resource. */
        }
        else
            frPtr->fileState.attributes = gAppWindowAttr;
                /* Set window attributes for the main document type. If the document
                ** is not the main type, then the application's InitDocument function
                ** will have to change it. */

        frPtr->fileState.getDocWindow        = windowPlacementProc;
        frPtr->fileState.adjustMenuItemsProc = AdjustMenuItems;
        frPtr->fileState.doMenuItemProc      = DoMenuItem;
        switch (frPtr->fileState.attributes & (kwIsPalette | kwIsModalDialog)) {
            case kwIsPalette:
                frPtr->fileState.calcFrameRgnProc  = PaletteCalcFrameRgn;
                frPtr->fileState.contentClickProc  = PaletteContentClick;
                frPtr->fileState.contentKeyProc    = PaletteContentKey;
                frPtr->fileState.drawFrameProc     = PaletteDrawFrame;
                frPtr->fileState.freeDocumentProc  = PaletteFreeDocument;
                frPtr->fileState.freeWindowProc    = PaletteFreeWindow;
                frPtr->fileState.imageProc         = PaletteImageDocument;
                frPtr->fileState.initContentProc   = PaletteInitContent;
                frPtr->fileState.readDocumentProc  = nil;
                frPtr->fileState.resizeContentProc = PaletteResizeContent;
                frPtr->fileState.scrollFrameProc   = PaletteScrollFrame;
                frPtr->fileState.undoFixupProc     = PaletteUndoFixup;
                frPtr->fileState.windowCursorProc  = PaletteWindowCursor;
                frPtr->fileState.writeDocumentProc = nil;
                break;
            case kwIsModalDialog:
                frPtr->fileState.calcFrameRgnProc    = DialogCalcFrameRgn;
                frPtr->fileState.contentClickProc    = DialogContentClick;
                frPtr->fileState.contentKeyProc      = DialogContentKey;
                frPtr->fileState.drawFrameProc       = DialogDrawFrame;
                frPtr->fileState.freeDocumentProc    = DialogFreeDocument;
                frPtr->fileState.freeWindowProc      = DialogFreeWindow;
                frPtr->fileState.imageProc           = DialogImageDocument;
                frPtr->fileState.initContentProc     = DialogInitContent;
                frPtr->fileState.readDocumentProc    = nil;
                frPtr->fileState.resizeContentProc   = DialogResizeContent;
                frPtr->fileState.scrollFrameProc     = DialogScrollFrame;
                frPtr->fileState.undoFixupProc       = DialogUndoFixup;
                frPtr->fileState.windowCursorProc    = DialogWindowCursor;
                frPtr->fileState.writeDocumentProc   = nil;
                frPtr->fileState.adjustMenuItemsProc = DialogAdjustMenuItems;
                frPtr->fileState.doMenuItemProc      = DialogDoMenuItem;
                break;
            default:
                frPtr->fileState.calcFrameRgnProc  = CalcFrameRgn;
                frPtr->fileState.contentClickProc  = ContentClick;
                frPtr->fileState.contentKeyProc    = ContentKey;
                frPtr->fileState.drawFrameProc     = DrawFrame;
                frPtr->fileState.freeDocumentProc  = FreeDocument;
                frPtr->fileState.freeWindowProc    = FreeWindow;
                frPtr->fileState.imageProc         = ImageDocument;
                frPtr->fileState.initContentProc   = InitContent;
                frPtr->fileState.readDocumentProc  = ReadDocument;
                frPtr->fileState.resizeContentProc = ResizeContent;
                frPtr->fileState.scrollFrameProc   = ScrollFrame;
                frPtr->fileState.undoFixupProc     = UndoFixup;
                frPtr->fileState.windowCursorProc  = WindowCursor;
                frPtr->fileState.writeDocumentProc = WriteDocument;
                break;
        }

        frPtr->fileState.windowSizeBounds.left   = kMinWindowWidth;
        frPtr->fileState.windowSizeBounds.top    = kMinWindowHeight;
        frPtr->fileState.windowSizeBounds.right  = kMaxWindowWidth;
        frPtr->fileState.windowSizeBounds.bottom = kMaxWindowHeight;
            /* Default min/max window size for growIcon. */

        pstr = frPtr->fileState.fss.name;
        pcpy(pstr, untitled);
        if (pstr[0]) {
            if (incTitleNum)
                ++untitledCount;
            pcatdec(pstr, untitledCount);
                /* Create the default document title.  It is stored in the FSSpec,
                ** as we can't place it in the window title.  We don't have a window
                ** yet to "title".  This will happen later.  The title is gotten from
                ** the FSSpec, so we are effectively done. */
        }

•••        err = InitDocument(frHndl);
            /* Call the application for any additional document initialization.
            ** Other handles may need to be allocated.  The default values above
            ** may be incorrect for certain document types.  This gives the
            ** application a chance to change any defaults that are incorrect. */

        if ((*frHndl)->fileState.sfType == MovieFileType) {
            movie = NewMovie(newMovieActive);
            err   = GetMoviesError();
            if (!err) {
                ClearMovieChanged(movie);
                (*frHndl)->fileState.movie = movie;
            }
        }

        if (err) {
            DisposeHandle((Handle)frHndl);
            if (returnHndl)
                *returnHndl = nil;
                    /* If the application couldn't complete the document
                    ** initialization, pitch the handle. */
        }
    }

    return(err);
}


Note the two lines marked with •••.  These two points the framework function
NewDocument() calls the application, which are:

1) The call to InitDocumentSize()
2) The call to InitDocument()


These two functions are part of your application.  (They are in the source file
File.c)  The first is called just so NewDocument() knows how big a handle to
create for the document reference.  If your application has only one document
type, then this function will simply return a constant.  If your application
has multiple document types, you will want to return the size that corresponds
to the document type (OSType).

Your application's function InitDocumentSize() is passed the OSType.  At this
point, the framework has only this piece of information on the document-to-be.
Until the application framework knows the size, it can't create the file
reference handle.  You tell the application framework how big to create the
frHndl.  It then creates it to the requested size, and initializes it to 0's and
default values.

Once it is initialized to defaults, NewDocument() calls your application, giving
it a chance to change the default values.  Only the frHndl is passed to
InitDocument().  The frHndl from this point on is the document reference.

If you have different document types, you will have to have a reasonably smart
InitDocument() function.  It will have to look at the document type, and then
adjust the default values for the frHndl based on the document type.  At this
point, the document type is stored in the frHndl, in the field fileState.sfType.

All of this is done prior to a window being created for the frHndl.  This is
important, as a number of the procedure pointers determine how the window will
be created.  You need to make customizations to the frHndl after its creation,
and prior to the creation of the document's window.

Of course, if your application only has one document type, then these defaults
are just fine, and you won't have to worry about all of this stuff.

The NewDocument() is pretty big, but that means that you don't have to worry
about this stuff.  The NewDocument() function is in charge of creating a
functioning frHndl.  The only thing your application has to do is to say how
big it should be, and what defaults you didn't like.


Let's revisit the code for a "New" menu item choice:


        err = NewDocument(&frHndl, gAppWindowType, true);
        if (!err) {
            err = DoNewWindow(frHndl, nil, FrontWindow(), (WindowPtr)-1);
            if (err)
                DisposeDocument(frHndl);
        }
        if (err)
            CenteredAlert(rErrorAlert, nil, (ModalFilterProcPtr)AlertFilter);
        break;


We have explored what happens when NewDocument() is called.  All that remains
is the DoNewWindow() call.


A window is opened for the frHndl.  The values stored in the frHndl are used
to determine how to open the window.

In the sample call above, we create a window for the document frHndl.  Here's
what the parameters indicate:

nil:            Don't bother returning a reference to the window created.
                If we cared, we might pass in something like &newWindow.
FrontWindow():    Window is created on the same monitor that holds most of the
                current front window.
(WindowPtr)-1:    Window is created as the front-most window.


That's all there is to it.  Now all you need is a way to hold your document
data.


Interestingly enough, DTS.framework has plenty of document support.  You can
use the hierarchical document architecture built into DTS.framework.  It is
very powerful.  It handles file I/O, hierarchically related data, infinite
undo, etc.


The hierarchical document architecture is the default type of document.  If
you choose to use it, there are already calls supplied to create the initial
default document.  All you have to do is to call DefaultInitDocument() in
your application's InitDocument() function.  For all documents that use the
hierarchical document architecture, simply call DefaultInitDocument() from
within InitDocument().

What DefaultInitDocument does is it creates a root object of type TreeObjHndl
and places it in an expected location within the frHndl for the document.
Consider this as a document within a document.  The frHndl describes the
run-time aspects of the document.  The root object in the hierarchy begins
the portion of the document that "persists", that is, saves to disk.

The root object is just that.  Yes, it has a data portion to it, but the main
purpose of the root object is a holder of the "child" objects of the document.

Whenever you make a change to the document, you will make it to some number of
objects with the hierarchy.  There are specific calls for this, and if you stick
to these calls, infinite undo works automatically.  There is a separate document
describing the hierarchical document architecture.  You will find it in the
DTS.Lib folder.  It is called "=Using TreeObj.c".  It will detail everything
you need to know about using the hierarchical document package.

Let's review the chain of information for a document, startiong with the window:

window:        References the document (frHndl) associated with the window.
            The reference to the frHndl is kept in the window's refcon field.

frHndl:        References back to the window.  This means that if you have either
            the window or the frHndl for a document, you can easily get the
            other.

            Also references the root hierarchy object.  This is true only if you
            elect to use the TreeObj package in the DTS.framework.  DTS.Draw
            uses this package heavily.  Wannabe also uses it, but has no objects
            defined, as Wannabe is only an application shell.


root:        References the frHndl that contains it.

            Also references the undo root object that contains all of the
            information necessary to undo/redo edits to the document.

            References all of the children added to the root object.


child:        References all children it may in turn have.

            References the parent object.  The root object can also be
            considered a child, but it is a child with no parent.  This
            is reflected in the parent reference.  If the parent reference
            is nil, then the object is a root object.


This is a nice top-down view of where document/window information is stored.
Here's some more information:

frHndl information is NOT saved with the document.  Any information you wish
to be saved with the document must be contained in a hierarchy object.

Changes to the root object can't be undone.  The location in the document
that is automatically kept for undo/redo operations is referenced by parent
and child number.  This locates you to any object within the hierarchy,
except for one.  The root object has no parent, so the location of the root
object can not be indicated by parent/childNum.

This means:

• Any information that is run-time, and you DON'T want saved to disk should be
  kept directly in the frHndl.
• Any information that you want to keep with the document, but you don't want
  involved in undo/redo operations should be kept in the root object.
• Any information that you want to be able to save and undo/redo in the
  document should be kept in a child below the level of the root object.


Of course, all of the rules from the root object down imply that you are using
the hierarchical document architecture.  This is a completely optional package.
All other rules continue to apply, whether or not you are using this package.




With the exception of the root object, all of the above information is kept in
the fileState portion of an frHndl.  The root object begins the actual document,
so it is actually in the document portion of an frHndl.  Why am I talking about
frHndl portions?  Because an frHndl is comprised of three distinct structures.
They are:

FileStateRec:    This is most adequately covered above.
ConnectRec:        This hasn't even been mentioned.
TheDoc:            This has been hinted at.


The ConnectRec portion of a document record looks like this:

typedef struct {
    long            windowID[2];        /* Used to match up windows. */
    short            endSendInfo;        /* Above is send info.         */

    Boolean            connected;            /* Flag showing we are connected.      */
    AEAddressDesc    remoteLoc;            /* AppleEvent address of remote user. */
    Str32            remoteName;            /* Name of user connected to.          */
    Str32            remoteZone;            /* Zone of user connected to.          */
    Str32            remoteMachine;        /* Machine name of user connected to. */
    short            endLocalInfo;        /* Above info is for 1 machine only.  */
} ConnectRec;

The ConnectRec is used by DTS.framework to establish a connection to
another application (or itself).  This connection links two specific windows.
Once connected, the boolean 'connected' is set true, and the other fields
are filled in.  The AEAddressDesc of whom you connected to is saved.  The name,
zone, and machine name are also kept.  The endLocalInfo field is a reference
point to determine the end of the ConnectRec at run-time.  This is here in case
there are additional fields added in the future.  They would be added before the
endLocalInfo field.  Since the ConnectRec structure is DTS.framework's
responsibility to maintain, you don't have to worry about this.  (I do.)


To see how to use the Apple Event facilities of DTS.framework, check out the
application Wannabe.  It uses these facilities.



The final component of an frHndl is the document portion.  It looks like this:


typedef struct {
    DocHeaderInfo    fhInfo;  /* Doc hdr info (vers, prRec, window loc.) */
    TreeObjHndl        root;
} TheDoc;


where DocHeaderInfo looks like this:


typedef struct {
    short        version;            /* The file format version.                   */
    Boolean        printRecValid;        /* True if prRec has been created.           */
    TPrint        print;                /* Print record for file.                   */
    Rect        structureRect;        /* Remember where window was when saved.   */
    Rect        contentRect;        /* Remember where window was when saved.   */
    Rect        stdState;            /* This and below rect used for saving       */
    Rect        userState;            /* zoom information for window.               */
    long        hDocSize;            /* hDocSize and vDocSize have to be saved  */
    long        vDocSize;            /* with the document, or recalculated       */
                                    /* when the file is opened so that the       */
                                    /* window can be created the correct size. */
    short        endDocHeaderInfo;    /* End version, print, and window info.       */
} DocHeaderInfo;


I suppose you figured that the document portion was your domain.  Well, it is,
kind of.  Since DTS.framework supplies hierarchical document support, it has
to have access to this portion of the frHndl, as well.  You always need the
fhInfo field of the document portion.  Also, it must be the first field in
the structure.

Note the comment on the hDocSize and vDocSize fields.  You can instruct the
framework to save the DocHeaderInfo structure automatically with the document,
in either the data fork or the resource fork.  If you choose this option,
then you don't have to worry about saving them or recalculating them.  You
will still have to initialize them to something appropriate whenever you
create a new document, however.

You optionally need the root field.  If you are using the hierarchical document
package, then you must have this field, and it must be the second field.

Aside from these two rules, the structure is all yours.  You can add as much as
you wish to it.


As has been described above, a single frHndl consists of three components.
These are:
    1) FileStateRec
    2) ConnectRec
    3) The document record.

The way you assemble these parts into a single frHndl is like this:


typedef struct FileRec {
    FileStateRec    fileState;        /* DTS.Lib expects this structure here. */
    ConnectRec        connect;        /* DTS.Lib expects this structure here. */
    union {
        TheDoc    doc;                /* Union in each document type here. */
    } d;
} FileRec;


This combines the three documents parts into a single structure.  Note the use
of union for the actual document portion.  This is because you can have multiple
document types within your application.  Whenever you add a document type, just
create a structure for it, and then union in this new structure into the FileRec
definition.  That's all there is to it (sort of).

You have to remember to change the InitDocumentSize() and InitDocument()
functions so that they can handle the new document type.  Once this is done,
you now have a new document type added to your application.


I think this should give you a good feel of what you need to first, second, etc.
Any other questions about using DTS.Lib and Wannabe should be answered in other
read.me files.  Of course, you can always look at the sample applications
DTS.Draw and Wannabe for implementation-specific details.



NOTE!!    The above is very good information as to how Wannabe and the application
        framework actually function.  However, a programming utility has been
        written that automates the above.  This utility is called AppsToGo.
        Use it.  The heck with code.  AppsToGo allows you to use Wannabe and the
        framework without having to code for a while.  Eventually you will have
        prototyped all the functionality possible and you will have to write
        some lines of code.  However, AppsToGo allows you to defer coding for
        quite some time.
        The changes to Wannabe that you make with AppsToGo are permanent, and
        adding code to Wannabe doesn't prevent you form continuing to use
        AppsToGo.  CHECK IT OUT!!


Eric Soldan